home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / softwareupdate / system / amigados / filefunctions / filefunctions.doc < prev    next >
Text File  |  1996-10-10  |  18KB  |  550 lines
  1. 3    FILE FUNCTIONS
  2.  
  3. 3.1  INTRODUCTION
  4.  
  5. In this chapter I will describe some useful file functions you
  6. might need when you are working with AmigaDOS:
  7.  
  8.   1. Create directories
  9.   2. Delete files and directories
  10.   3. Rename files and directories
  11.   4. Rename volumes
  12.   5. Attach comments to files and directories
  13.   6. Alter the "protection bits" on files and directories
  14.  
  15.  
  16.  
  17. 3.2  CREATE DIRECTORIES
  18.  
  19. To create directories you use the function "CreateDir()". You
  20. only need to give the function a string with the name of the
  21. new directory (including any necessary path), and the directory
  22. will automatically be created. If the directory could
  23. successfully be created an exclusive lock to the new directory
  24. is returned, else if there was an error and the directory could
  25. not be created NULL is returned.
  26.  
  27. Since the directory is automatically locked if it was created
  28. you have to unlock it yourself as soon as you do not need the
  29. lock any more.
  30.  
  31. If there already exist a directory with the same name the
  32. function will fail.
  33.  
  34. ---------------------------------------------------------------
  35.  
  36. CreateDir()
  37.  
  38. ROM library: "dos.library/CreateDir", (All versions)
  39. #include <clib/dos_protos.h>
  40.  
  41. Creates a directory and puts an exclusive lock on it.
  42.  
  43. Synopsis: lock = CreateDir( dir_name );
  44.  
  45.   lock:     (BPTR) If the directory could be created or there
  46.             already exist a direcoty with the specified name
  47.             a BPTR (BPCL pointer) is returned. If the directory
  48.             on the other hand could not be created NULL is
  49.             returned.
  50.             
  51.   dir_name: (STRPTR) Pointer to a text string which contains
  52.             the name of the new directory (including any
  53.             necessary path).
  54.  
  55. If you have successfully created a directory you must unlock it
  56. as soon as you do not need the lock any more!
  57.  
  58. Here is a simple example on how to use the CreateDir()
  59. function:
  60.  
  61.   /* A "BCPL" pointer to our directory lock: */
  62.   BPTR my_dir_lock;
  63.  
  64.   - - -
  65.  
  66.   /* Try to create a directory: */
  67.   my_dir_lock = CreateDir( "Ram:MyDirectory" );
  68.  
  69.   /* Check if we have successfully created */
  70.   /* the directory or not:                 */
  71.   if( my_dir_lock == NULL )
  72.   {
  73.     /* Problems! */
  74.     printf( "Could not create the directory!\n" );
  75.     exit( 20 );
  76.   }
  77.  
  78.   - - -
  79.   
  80.   /* When we do not need the directory lock */
  81.   /* any more we unlock it:                 */
  82.   UnLock( my_dir_lock );
  83.  
  84.  
  85. See also: Lock(), UnLock()
  86.  
  87. ---------------------------------------------------------------
  88.  
  89.  
  90. 3.3  DELETE FILES AND DIRECTORIES
  91.  
  92. When you want to delete a file or directory you should use the
  93. "DeleteFile()" function. You only need to give the function a
  94. string with the name of the file or directory you want to delte
  95. (including any necessary path). If the file/directory could be
  96. deleted TRUE is returned, else FALSE is returned (file could
  97. not be deleted).
  98.  
  99. Note that you can only delete a directory which is empty.
  100.  
  101. ---------------------------------------------------------------
  102.  
  103. DeleteFile()
  104.  
  105. ROM library: "dos.library/DeleteFile", (All versions)
  106. #include <clib/dos_protos.h>
  107.  
  108. Deletes a specified file or directory.
  109.  
  110. Synopsis: ok = DeleteFile( name );
  111.  
  112.   ok:     (LONG) If the file/directory could be deleted TRUE is
  113.           returned, else FALSE is returned (the file/directory
  114.           could not be deleted).
  115.             
  116.   name:   (STRPTR) Pointer to a text string which contains
  117.           the name (including any necessary path) of the file
  118.           or directory you want to delete.
  119.           
  120. Remember that you can only delete empty directories.
  121.  
  122. Here is a simple example on how to use the DeleteFile()
  123. function:
  124.  
  125.   /* A simple boolean variable: */
  126.   BOOL ok;
  127.  
  128.   /* Delete a file: */
  129.   ok = DeleteFile( "RAM:Unimportand.dat" );
  130.  
  131.   /* Could we delete the file? */
  132.   if( ok )
  133.     printf( "File deleted!\n" );
  134.   else
  135.     printf( "File could not be deleted!\n" );
  136.  
  137.  
  138. See also: Open(), CreateDir()
  139.  
  140. ---------------------------------------------------------------
  141.  
  142.  
  143.  
  144. 3.3  RENAME FILES AND DIRECTORIES
  145.  
  146. When you want to rename a file or directory you should use the
  147. "Rename()" function. You can even move a file or directory
  148. to other directories on a volume by simply renaming the path
  149. accordingly. For example:
  150.   
  151.   /* Move a file inside a volume: OK! */
  152.   Rename( "df0:Documents/Sale.doc", "df0:Letters/Sale.doc" );
  153.  
  154. We have now moved the file "Sale.doc" from the directory
  155. "Documents" to directory "Letters". Note! You can not rename a
  156. file from one volume to another, you can only move the file or
  157. directory inside the volume. Here is an example that will not
  158. work:
  159.  
  160.   /* Try to move a file to another volume: INCORRECT! */
  161.   Rename( "df0:Documents/Sale.doc", "df1:Letters/Sale.doc" );
  162.  
  163. If you move a directory all objects (files and subdirectories)
  164. will also be moved accordingly.
  165.  
  166. ---------------------------------------------------------------
  167.  
  168. Rename()
  169.  
  170. ROM library: "dos.library/Rename", (All versions)
  171. #include <clib/dos_protos.h>
  172.  
  173. Renames a specified file or directory. It is possible to rename
  174. a file or directory so it is moved to another location on the
  175. same volume.
  176.  
  177. Synopsis: ok = Rename( old_name, new_name );
  178.  
  179.   ok:       (LONG) If the file/directory could be renamed TRUE
  180.             is returned, else FALSE is returned (the file/
  181.             directory could not be renamed).
  182.             
  183.   old_name: (STRPTR) Pointer to a text string which contains
  184.             the name (including any necessary path) of the file
  185.             or directory you want to rename.
  186.  
  187.   new_name: (STRPTR) Pointer to a text string which contains
  188.             the new name (including any necessary path) of the
  189.             file or directory. The path may be different as
  190.             long as it is still on the same volume.
  191.           
  192. Note, you can not rename a file or directory to another volume!
  193.  
  194. You can not rename a volume with this function. You must then
  195. instead use the new "Relabel()" function.
  196.  
  197. Here is a simple example on how to use the Rename() function:
  198.  
  199.   /* A simple boolean variable: */
  200.   BOOL ok;
  201.  
  202.   /* Rename a file: (We not only rename the actual file, but  */
  203.   /* we also move the file inside a directory called "MyDir") */
  204.   ok = Rename( "RAM:HorribleName.doc", "RAM:MyDir/Good.doc" );
  205.  
  206.   /* Could we rename the file? */
  207.   if( ok )
  208.     printf( "File renamed!\n" );
  209.   else
  210.     printf( "File could not be renamed!\n" );
  211.  
  212.  
  213. See also: Relabel()
  214.  
  215. ---------------------------------------------------------------
  216.  
  217.  
  218.  
  219. 3.4  RENAME VOLUMES (RELABEL)
  220.  
  221. When you want to rename a volume you can not use the previously
  222. discussed "Rename()" function. Instead you have to use a
  223. function called "Relabel()" which was introduced with Release
  224. 2. Before you may use this function you must therefore make
  225. sure that the user really has dos version 36 or higher!
  226.  
  227. ---------------------------------------------------------------
  228.  
  229. Relabel()
  230.  
  231. ROM library: "dos.library/Relabel", (V36+)
  232. #include <clib/dos_protos.h>
  233.  
  234. Renames a specified volume.
  235.  
  236. Synopsis: ok = Relabel( old_name, new_name );
  237.  
  238.   ok:       (LONG) If the volume could be renamed TRUE is
  239.             returned, else FALSE is returned (the volume could
  240.             not be renamed).
  241.             
  242.   old_name: (STRPTR) Pointer to a text string which contains
  243.             the name of the volume you want to rename. Since
  244.             this is the current volume name you have to include
  245.             the colons ":" at the end of the volume name.
  246.             
  247.   new_name: (STRPTR) Pointer to a text string which contains
  248.             the new name of the volume. There should NOT be any
  249.             colons (:) at the end of this name since it is for
  250.             the moment not a volume name (but it will hopefully
  251.             soon be).
  252.           
  253. Note that this function was first included in dos library V36!
  254.  
  255. You can only rename volumes with this function. To rename a
  256. file or directory you have to use the "Rename()" function.
  257.  
  258. Here is a simple example on how to use the Relabel() function:
  259.  
  260.   /* A simple boolean variable: */
  261.   BOOL ok;
  262.  
  263.   /* Rename the device: (We will try to rename the volume */
  264.   /* "Programs:" to "SourceCode".)                        */
  265.   ok = Relabel( "Programs:", "SourceCode" );
  266.  
  267.   /* Could we rename the volume? */
  268.   if( ok )
  269.     printf( "The volume was successfully renamed!\n" );
  270.   else
  271.     printf( "The volume could not be renamed!\n" );
  272.  
  273.  
  274. See also: Rename()
  275.  
  276. ---------------------------------------------------------------
  277.  
  278.  
  279.  
  280. 3.5  ATTACH COMMENTS TO FILES AND DIRECTORIES
  281.  
  282. AmigaDOS allows you to set a comment on a file or directory.
  283. The comment can give the user a brief description of what the
  284. file contains, or who created it etc... This comment is very
  285. handy to use when you want to give some extra information about
  286. the file, and since you can connect a comment which is up to 80
  287. characters long even rather long descriptions can be used.
  288.  
  289. The user can display a comment on a file or directory by using
  290. the Shell (CLI) command "List":
  291.  
  292.   1.Prog:>
  293.   1.Prog:> List df0:SourceCodes
  294.   Directory "df0:SourceCodest" on Monday 15-Mar-93
  295.   Miniblast.c              34155 ----rwed 12-Jan-93 23:35:20
  296.   : This version can be used on all Amigas! Still a bug on line 365!!! -AB-
  297.   Macroblast.c            299128 ----rwed 16-Jan-93 03:35:12
  298.   : Connects fine, prob. with unknown PubScreen, otherwise OK! -AB-
  299.   LockSystem.c             24899 ----rwed 04-Feb-93 01:45:34
  300.   : Has to be updated before use! Line 512 & 525, ok code, -AB-
  301.   and so on...
  302.  
  303. To set a comment on a file or directory you should use the
  304. "SetComment()" function.
  305.  
  306. ---------------------------------------------------------------
  307.  
  308. SetComment()
  309.  
  310. ROM library: "dos.library/SetComment", (All versions)
  311. #include <clib/dos_protos.h>
  312.  
  313. Adds a comment to a file or direcotry.
  314.  
  315. Synopsis: ok = SetComment( file_name, comment );
  316.  
  317.   ok:      (LONG) If the comment could be attached to the file
  318.            or directory TRUE is returned, else FALSE is
  319.            returned (the comment could not be attached).
  320.  
  321.   name:    (STRPTR) Pointer to a text string which contains
  322.            the name (including any necessary path) of the file
  323.            or directory you want to add the comment to.
  324.  
  325.   comment: (STRPTR) Pointer to a text string which contains
  326.            the comment you want to add. The comment can be up
  327.            to 80 characters long. (Any old comment will be
  328.            replaced.)
  329.  
  330. Here is a simple example on how to use the SetComment()
  331. function:
  332.  
  333.   /* A simple boolean variable: */
  334.   BOOL ok;
  335.  
  336.   /* Add a comment to the file: */
  337.   ok = SetComment( "Ram:Hello.c", "My wonderful program!" );
  338.  
  339.   /* Was the comment successfully added? */
  340.   if( ok )
  341.     printf( "The comment was successfully attached!\n" );
  342.   else
  343.     printf( "Error! Could not add the comment!\n" );
  344.  
  345.  
  346. See also:
  347.  
  348. ---------------------------------------------------------------
  349.  
  350.  
  351.  
  352. 3.6  ALTER THE PROTECTION FLAGS
  353.  
  354. All files and directories have a field of bits which is called
  355. "the protection bits". The bits can be turned on or off and it
  356. will affect other programs that may use the files. The most
  357. commonly used bit is bit 0 which tells AmigaDOS if the file or
  358. directory may be deleted or not. This is the "delete" bit, and
  359. since it is so commonly used the whole collection of bits has
  360. been called "the protection bits" although the other bits have
  361. nothing to do with protecting the file from being deleted.
  362.  
  363. The user can alter the bits with help of the Shell (CLI)
  364. command "Protect". Here is the list of protection flags the
  365. user can use (each flag will alter its corresponding bit):
  366.  
  367.   Flag Description
  368.   -------------------------------------------------------------
  369.     s  The file is a "script" and contains Shell commands. If
  370.        the user enter the name of a file with this flag set
  371.        will the file automatically be executed as a script. The
  372.        user do not have to add the Shell command "Execute" in
  373.        front of the file name.
  374.        
  375.     p  The file is "pure" and can therefore be made "resident".
  376.        If this falg is not set the Shell command "Resident"
  377.        will fail.
  378.  
  379.     a  The file has been archived. Everytime a file has been
  380.        modified this flag is removed. The flag is usually used
  381.        by backup programs which set this flag each time the
  382.        file has been archived.
  383.     
  384.     r  The file can be read by other programs. If this flag is
  385.        not set the file can not be read.
  386.  
  387.     w  The file can be altered by other programs. If this flag
  388.        is not set the file can not be altered.
  389.  
  390.     e  The file is "executable" (a normal program). If this
  391.        flag is not set Shell (CLI) will refuse to start the
  392.        file as a program.
  393.  
  394.     d  The file/directory can be deleted. If this flag is not
  395.        set the file can not be deleted.
  396.  
  397. Most of these flags are only useful for files, but it is
  398. possible to use all of then on directories too even if most of
  399. them will not have any effect on the directory.
  400.  
  401. Here is an exapmple on how the user can protect a file from
  402. being accidentally deleted:
  403.  
  404.   1.Prog:>
  405.   1.Prog:> Protect df0:Important.dat SUB d
  406.  
  407. To see which flags are set or not the user can call the Shell
  408. (CLI) command "List":
  409.  
  410.   1.Prog:>
  411.   1.Prog:> List df0:
  412.   Directory "df0:" on Monday 15-Mar-93
  413.   Important.dat           128722 ----rwe- 21-Feb-93 02:12:18
  414.   NotSoImportant.dat      103677 ----rwed 21-Feb-93 02:12:25
  415.   and so on...
  416.  
  417. As you can see has the "d" flag been removed, and the file can
  418. then not be deletet. The only way to delete the file is to add
  419. the "d" flag again and then delete the file.
  420.  
  421. If the flag is used by AmigaDOS depends on which version the
  422. user has:
  423.  
  424.   -------------------------------------------------------------
  425.     s  Used by the Shell & CLI (WB 1.3 or higher). If the flag
  426.        is set the file will be executed as a script. (You do
  427.        no need to use the Shell command "Execute".)
  428.     p  Used by Shell's (CLI's) "Resident" command (WB 1.3 or
  429.        higher). If the flag is set the file (program) can be
  430.        made "resident".
  431.     a  Used by all AmigaDOS versions and the FFS. Every time
  432.        the file has been altered this flag is removed.
  433.     r  Used by AmigaDOS V36 or higher and by the FFS. If it is
  434.        not set the file can not be read.
  435.     w  Used by AmigaDOS V36 or higher and by the FFS. If it is
  436.        not set the file can not be altered.
  437.     e  Used by the Shell & CLI (all AmigaDOS versions and the
  438.        FFS), if the flag is not set Shell and CLI refuses to
  439.        start it.    
  440.     d  Used by all AmigaDOS versions and the FFS. If it is not
  441.        set the file can not be deleted.
  442.   -------------------------------------------------------------
  443.  
  444. To alter the protection bits from C you should use the function
  445. "SetProtection()".
  446.  
  447. ---------------------------------------------------------------
  448.  
  449. SetProtection()
  450.  
  451. ROM library: "dos.library/SetProtection", (All versions)
  452. #include <clib/dos_protos.h>
  453.  
  454. Alters the protection bits on a file or directory.
  455.  
  456. Synopsis: ok = SetComment( file_name, flags );
  457.  
  458.   ok:     (LONG) If the protection bits could be altered as
  459.           instructed the function returns TRUE, else FALSE is
  460.           returned (the protection bits could not be altered).
  461.  
  462.   name:   (STRPTR) Pointer to a text string which contains
  463.           the name (including any necessary path) of the file
  464.           or directory which protection bits you want to
  465.           alter.
  466.  
  467.   flags:  (LONG) The protection bits you want to alter. You
  468.           set and/oor removes the bits with help of the
  469.           following flags: (defined in header file
  470.           "dos/dos.h")
  471.   
  472.             FIBF_DELETE:
  473.                  If this flag is set the "d" bit is removed so
  474.                  the file or directory can not be deleted. If
  475.                  this flag is not set the "d" bit will be
  476.                  added.
  477.                  
  478.             FIBF_EXECUTE:
  479.                  If this flag is set the "e" bit is removed so
  480.                  Shell (CLI) will refuse to start the file as a
  481.                  program. If this flag is not set the "e" bit
  482.                  will be added.
  483.  
  484.             FIBF_WRITE:
  485.                  If this flag is set the "w" bit is removed so
  486.                  no one can alter the file. If this flag is not
  487.                  set the "w" bit will be added.
  488.                  
  489.             FIBF_READ:
  490.                  If this flag is set the "r" bit is removed so
  491.                  no one can read the file. If this flag is not
  492.                  set the "r" bit will be added.
  493.                  
  494.  
  495.             FIBF_ARCHIVE:
  496.                  If this flag is set the "a" bit will be added
  497.                  which indicates that the file has been
  498.                  archived. If this flag is not set the "a" bit
  499.                  will be removed.
  500.  
  501.             FIBF_PURE:
  502.                  If this flag is set the "p" bit will be added
  503.                  which tells the Shell command "Resident" that
  504.                  this file is "pure" and can be made resident.
  505.                  If this flag is not set the "p" bit will be
  506.                  removed.
  507.  
  508.             FIBF_SCRIPT:
  509.                  If this flag is set the "s" bit will be added
  510.                  which tells Shell that this file is a script.
  511.                  If this flag is not set the "s" bit will be
  512.                  removed.
  513.  
  514.             Note that the first four flags will remove the
  515.             corresponding bits if the flags are set. The last
  516.             three flags will on the other hand set the
  517.             corresponding bits if the flags are set!
  518.  
  519.             To set sveral flags simply add a "|" sign between
  520.             them. So to protect a file from being accidentally
  521.             deleted and to instruct the Shell that it is a
  522.             script you set this field to:
  523.               FIBF_DELETE | FIBF_SCRIPT
  524.  
  525.             Note that the "e", "w" and "r" bits will also
  526.             be set and "a" and "p" removed!
  527.  
  528. Here is a simple example on how to use the SetProtection()
  529. function:
  530.  
  531.   /* A simple boolean variable: */
  532.   BOOL ok;
  533.  
  534.   /* Protect the file from being accidentally deleted */
  535.   /* and tell Shell it is a script:                   */
  536.   ok = SetProtection( "S:PrepCompiler",
  537.     FIBF_DELETE | FIBF_SCRIPT );
  538.  
  539.   /* Could we alter the protection bits as desired? */
  540.   if( ok )
  541.     printf( "The protection bits were successfully altered!\n" );
  542.   else
  543.     printf( "Error! Could not alter the protection bits!\n" );
  544.  
  545.  
  546. See also:
  547.  
  548. ---------------------------------------------------------------
  549.  
  550.